CU Amiga Super CD-ROM 27/CU Amiga Magazine's Super CD-ROM 27 (1998)(EMAP Images)(GB)[!][issue 1998-10].iso/GoodBye/JohnKennedy/December94.lha/crimbo2.lha/master.doc

Text File | 1994-10-14 | 12.3 KB | 358 lines

AmigaDos MasterClass - December 1994



You've probably seen them, you've probably used them - noew
John Kennedy explains how to write them: AmigaGuide
documents.



Despite what you might think, Commodore do occasionally have
good ideas, and there are three which really stick out when
I use my system. The first brainwave was to make ARexx part
of the Workbench with release 2.04 upwards. As we saw last
month, ARexx helps make the most of the Amiga's operating
system and opens up all sorts of possibilities which
other platforms can only dream about.

The second idea was to create Installer - a user-friendly
and universally supported program for installing software
onto hard disks. Any vendor (shareware, freeware or
commercial) can supply Installer and use an easy-to-write
script that makes setting up applications and games a
pleasure.

The third idea was AmigaGuide - the hypertext, on-line help
and documentation system. Now this was a really Good Thing -
at last a standard way of displaying documents without all
the silly hassles of using text display programs like More
and PPMore. It's not new - there are similar systems on the
PC and Mac, but in the typical Amiga way, it's better.

AmigaGuide can be used as nothing more than a text display
system, but when you start to use the embedded command codes
you can do all sorts - from making on-line help files to
interactive stories and even adventure games. I've also seen
an Internet Gopher tool written using AmigaGuide.

The 'hypertext' system is growning in popularity all the
time: one american company even tried to patent it, which
would have been interesting. If you have seen or used
Mosaic, the World Wide Web browser, you'll have an idea what
is possible.



Write your own
--------------


Writing your own AmigaGuide document is easy, but the first
thing to make sure of is that you have the AmigaGuide
display program or you'll be wasting your time. Hunt around
on your Workbench 3.0 disks for it, and make sure the
Amigaguide datatype is installed - this way you can use
Multiview to examine your documents.

If you don't have Workbench 3 (i.e. you don't have an A1200
or A4000 or an upgrade) hunt around for anything that says
AmigaGuide on some of your existing software.

(picture: guide1.jpg)
(caption: AmigaGuide is an easy to use hypertext system.
Many programs use it for on-line help.)

AmigaGuide looks like figure 1 when it is running. The
'buttons' are added by special codes embedded in the
document - an AmigaGuide file is nothing more than a text
file with some special codes in it. You can create it with
Ed, or CygnusEd or GoldEd or anyother plain ASCII text
editor.

The controls at the top are added automatically by the
AmigaGuide system. Normally the window will open on the
Workbench, and assume the largest size possible - but you
can re-size it and push it backwards and forwards as
necessary.

Here is the text behind that first example.

-----------------------------------------------------------------

@database "example"
@author "John Kennedy"
@(c) "Copyright © 1992 Commodore-Amiga, Inc. & 1994 John Kennedy"
@$VER: Example 0.1 (14/10/94)

@wordwrap

@Node Main "Welcome"
@{b}@{fg highlight}The CU Amiga Example Document @{fg text}@{ub}

@{" 1. Button 1 " link ex-1}
@{" 2. Button 2 " link ex-2}
@{" 3. Button 3 " link ex-3}

@ENDNODE

-----------------------------------------------------------------

As you can see, the special AmigaGuide codes appear after
the '@' signs. There are two types - commands like
'database' and 'wordwrap', and attributes: which always are
enclosed in curly brackets. Some code are pretty obvious,
others need a little more explaination.

The file must start with the Database word. The database is
simply the name of the file, and the author - well that's
you. This sort of information is only entered once at the
start of the file - think of it as a way of keeping track of
your AmigaGuide experiments.

AmigaGuide works by creating different 'pages' of
information. These pages contain text, but also links to
other pages. Whenever you click on the links the relevant
page is displayed. It is also possible to move between pages
using the buttons at the top of the page, but this is
handled automatically.

Each page is called a 'node' in AmigaGuide parlance, and to
create one you simply use the command @Node followed by the
node name and the title of the new page.

In the example, the Node is called 'Main' because it will be
the first page that is display. Always remember to call your
first page Main or nothing will be displayed! The title will
appear in the title bar of the AmigaGuide window.

Every node must have a matching Endnode - and sure enough,
that's the last line in the example. In between Node and
Endnode, there are a few tricky looking lines.

The first line after Node isn't so bad when you realise that
everything in the curly brackets is a special AmigaGuide
attribute code (see the box out for details). You should be
able to see that this line switched on bold text, and then
alters the colour. The text is then displayed on-screen, and
the bold and colour modes switched off. It is important to
remember that any text that appears by itself - without
codes - will be displayed on-screen.

The next three lines are all links to other (currently
non-existant nodes). At this point it becomes obvious that
planning your document from the outset it important, and it
is worth sketching down a few ideas.

Are you going to have the entire thing menu driven from the
start? This is quite a good way - all you need to do is
create a link to every page in the document, and the user
will quickly and easily be able to find their way to it.

Alternatively, you might want to create plain text with
occasional words acting as links - this approach is called
'hypertext' or 'non sequential reading' - and it is useful
when you use a lot of jargon in your work. If the user wants
more information, they can click on the high-lighted word
and a page containing more information or a definition will
be displayed.

Finally, you may want to create gadgets at the bottom of the
page for navigation purposes. For example, in a maze game
the words would be North, South, East and West - and a click
on each would bring the reader to a new page containing a
new description of your surroundings. You might want the use
to be able to skip several pages by creating a fast-forward
and reverse button at the bottom the page.

The best documents are a collection of all three methods. If
you have time, it is especially useful if you include an
alphabetical index in your document, highlighting all the
important words and phrases - more on this later.


Adding buttons



The first link line in the document looks like this:

@{" 1. Button 1 " link ex-1}

The text in the quotation marks is the text which will be
highlighted on-screen: the text which the user can click on
with the mouse.

The text after the word 'link' is the name of the node that
the AmigaGuide system should move to and display if the text
is clicked. In this example, if the user clicks on the text
'1. Button 1' then the node/page called 'ex-1' will be
displayed.

Here is our example again, but this time with a new node
which can be jumped to:

-----------------------------------------------------------------

@database "example"
@author "John Kennedy"
@(c) "Copyright © 1992 Commodore-Amiga, Inc. & 1994 John Kennedy"
@$VER: Example 0.1 (14/10/94)
@wordwrap
@Node Main "Welcome"
@{u}@{fg shine}The CU Amiga Example Document @{fg text}@{uu}

@{" 1. Button 1 " link ex-1}
@{" 2. Button 2 " link ex-2}
@{" 3. Button 3 " link ex-3}

@ENDNODE


@node ex-1 "This is Page 1"

Welcome to page 1. Page 1 has always been my favourite page,
as it offers the promise of much better stuff to come.

@endnode

-----------------------------------------------------------------


You can continue to add more and more pages like this. In
fact, you might find it easier to write the text first, and
then go back and add all the AmigaGuide codes. There are
even some utilitiy programs which attempt to make converting
existing documents into AmigaGuide format easier.

Adding links to words which are contained in sentences isn't
hard. Here is how to add another link to the word 'promise':


-----------------------------------------------------------------

Welcome to page 1. Page 1 has always been my favourite page,
as it offers the @{"promise" link promise-page} of much
better stuff to come.

-----------------------------------------------------------------

(picture:guide2.jpg)
(caption: Even words in sentences can be made into links -
clicking on 'promise' will display a definition.)

You can see that the text 'promise' will become highlighted,
and clicking on it will move it the page called
'promise-page'. This is how you can create a list of
definitions for words. Readers who know what the words
already mean won't have to re-read tedious explainations,
but new users can find out what is going on.

The buttons at the top of the screen include two called
CONTENTS and INDEX. The Contents button will light whenever
the user moves away from the MAIN page - and if they click on it,
the main page will be redisplayed.

In this way, no matter where they are in the document, there
is always a quick way back home to the start.

Likewise, if you create an index page make sure to call it
Index - if you do, the Index button will light and the user
can move there immediately as well.






New and Improved


If you are using a newer version of AmigaGuide (v40 or
better) there are extra codes available for you to use. To
discover which version you have, select ABOUT from the menu.
Keep a look out for newer versions of the AmigaGuide
datatype on existing software.

As well as extra codes, the improved AmigaGuide can handle
pictures and ARexx commands as well - which means it can do
just about everything. Here are some useful new commands:

@SMARTWRAP is new and replaces WORDWARP. It is better than
previous versions, so use it if you can.

@ONOPEN will execute an ARexx script when the node (page) is first
displayed.

@ONCLOSE will execute an ARexx script then the node is
closed.

@PLAIN switches off all italic, bold and underlined options
quicky and easily.

@NEXT
@PREVIOUS
@RETRACE   All are used to provide you with a way of make
buttons which emulate the options at the top of the screen.

There are various other options for altering the font, and
incorporating graphics but these will have to wait for
another time... in other words, I haven't got them working
yet!





Running your AmigaGuide document
--------------------------------



If you have found the AmigaGuide tool in your workbench
directories, you can use it you display your documents. Find
the icon for the document, and double-click on the
AmigaGuide tool - hey presto, up it should pop.

Alternatively, find the icon for the document and change the
tool type to read AmigaGuide. If this doesn't work, try
using Multiview instead, as Multiview can read AmigaGuide
documents (using the datatype) as well as displaying
pictures, animations and sound. In fact, Multiview and
Datatype are two more of Commodore's Good Ideas.


(picture:guide3.jpg)
(caption:Use the Workbench INFORMATION menu option to change
the default tool of the document to be AmigaGuide. If this
doesn't work, try MULTIVIEW (if you have Workbench 3 and the
AmigaGuide datatype installed.)





Box Out - Amiga Guide Options (all versions)
--------------------------------------------

@WordWrap               Switch on word-wrapping facility
@{b}                    Switch on bold text
@{ub}                   Switch off bold text
@{i}                    Switch on bold text
@{ui}                   Switch off bold text
@{u}                    Switch on underlined text
@{uu}                   Switch off underlined text
@{fg <flag>}            Switch foreground text to colour specifed by flag*
@{bg <flag>}            Switch background text to colour specifed by flag*
@{fg text}              Switch text to normal colour
@Node <name> <text>     Start a 'node' or page of text.
@Endnode                Stop a node.
@{ <text> link <node>   Create a link to a node.
@font <font> <size>     Start use the font with given size
@help                   The node displayed when the user presses HELP
@index                  The node displayed when the user clicks on CONTENTS
@title                  The text displayed at the top of the page.


* Text options include: Shine, Shadow, Fill, FillText,
Background, Highlight